.TH initctl 8 2009-07-09 "Upstart"
.\"
.SH NAME
initctl \- init daemon control tool
.\"
.SH SYNOPSIS
.B initctl
.RI [ OPTION ]...
.I COMMAND
.RI [ OPTION ]...
.IR ARG ...
.\"
.SH DESCRIPTION
.B initctl
allows a system administrator to communicate and interact with the Upstart
.BR init (8)
daemon.

When run as
.BR initctl ,
the first non-option argument is the
.IR COMMAND .
Global options may be specified before or after the command.

You may also create symbolic or hard links to
.B initctl
named after commands.  When invoked through these links the tool will
behave only as that command, with global and command-specific options
intermixed.  The default installation supplies such links
for the
.BR start ", " stop ", " restart " and " status
commands.
.\"
.SH OPTIONS
.TP
.B --system
Communication with the
.BR init (8)
daemon is normally performed over a private socket connection.  This has
the advantage of speed and robustness, when issuing commands to start or
stop services or even reboot the system you do not want to be affected by
changes to the D-Bus system bus daemon.

The disadvantage to using the private socket however is security,
.BR init (8)
only permits the root user to communicate over this socket which means
that read-only commands such as
.BR status " and " list
cannot be made by other users.

The
.B --system
option instructs
.BR initctl
to communicate via the D-Bus system bus rather than over the private
socket.

This is only possible if the system bus daemon is running and if
.BR init (8)
is connected to it.  The advantage is that the default security configuration
allows non-root users to use read-only commands.
.\"
.TP
.B --dest
Specifies the well-known name of the
.BR init (8)
daemon when using
.BR --system .

There is normally no need to use this option since the
.BR init (8)
daemon uses the default
.B com.ubuntu.Upstart
name.  However it may be useful for debugging.
.\"
.TP
.B --no-wait
Applies to the
.BR start ", " stop ", " restart " and " emit
commands.

Normally
.B initctl
will wait for the command to finish before returning.

For the
.BR start ", " stop " and " restart
commands, finishing means that the named job is running (or has finished
for tasks) or has been fully stopped.

For the
.B emit
command, finishing means that all of the jobs affected by the event
are running (or have finished for tasks) or have been fully stopped.

This option instead causes these commands to only wait for the goal
change or event to be queued.
.\"
.TP
.B --quiet
Reduces output of all commands to errors only.
.\"
.SH COMMANDS
.TP
.B start
.I JOB
.RI [ KEY=VALUE ]...

Requests that a new instance of the named
.I JOB
be started, outputting the status of the job to standard output when the
command completes.

See
.B status
for a description of the output format.

The optional
.I KEY=VALUE
arguments specify environment variables to be passed to the starting job,
and placed in its environment.  They also serve to specify which instance
of multi-instance jobs should be started.

Most jobs only permit a single instance; those that use the
.B instance
stanza in their configuration define a string expanded from environment
variables to name the instance.  As many unique instances may be started
as unique names may be generated by the stanza.  Thus the environment
variables also serve to select which instance of
.I JOB
is to be acted upon.

If the job is already running,
.B start
will return an error.
.\"
.TP
.B stop
.I JOB
.RI [ KEY=VALUE ]...

Requests that an instance of the named
.I JOB
be stopped, outputting the status of the job to standard output when the
command completes.

See
.B status
for a description of the output format and
.B start
for a discussion on instances.
.\"
.TP
.B status
.I JOB
.RI [ KEY=VALUE ]...

Requests the status an instance of the named
.IR JOB ,
outputting to standard output.

See
.B start
for a discusson on instances.

For a single-instance job a line like the following is output:

.nf
  job start/running, process 1234
.fi

The job name is given first followed by the current goal and state of
the selected instance.  The goal is either
.IR start " or " stop ,
the status may be one of
.IR waiting ", " starting ", " pre-start ", " spawned ", " post-start ", "
.IR running ", " pre-stop ", " stopping ", " killed " or " post-stop .

If the job has an active process, the process id will follow on the same
line.  If the state is
.IR pre-start " or " post-stop
this will be the process id of the equivalent process, otherwise it will
be the process id of the main process.

.nf
  job start/pre-start, process 902
.fi

The
.IR post-start " and " pre-stop
states may have multiple processes attached, the extra processes will follow
on consecutive lines indented by a tab:

.nf
  job start/post-start, process 1234
          post-start process 1357
.fi

If there is no main process, they may follow on the same line but will be
prefixed to indicate that it is not the main process id being given:

.nf
  job start/post-start, (post-start) process 1357
.fi

Jobs that permit multiple instances have names for each instance, the
output is otherwise identical to the above except that the instance
name follows the job name in parentheses:

.nf
  job (tty1) start/post-start, process 1234
          post-start process 1357
.fi
.\"
.TP
.B list

Requests a list of the known jobs and instances, outputs the status of
each to standard output.

See
.B status
for a description of the output format and
.B start
for a discussion on instances.

No particular order is used for the output, and there is no difference in
the output (other than the instance name appearing in parentheses) between
single-instance and multiple-instance jobs.
.\"
.TP
.B emit
.I EVENT
.RI [ KEY=VALUE ]...

Requests that the named
.I EVENT
be emitted, potentially causing jobs to be started and stopped depending
on their use of the
.BR "start on" " and " "stop on"
stanzas in their configuration.

The optional
.I KEY=VALUE
arguments specify environment variables to be included with the event and
thus exported into the environment of any jobs started and stopped by
the event.

The environment may also serve to specify which instance of multi-instance
jobs should be started or stopped.  See
.B start
for a discussion on instances.

There is no limitation on the event names that may be emitted with this
command, you are free to invent new events and use them in your job
configurations.

The most well known event used by the default Upstart configuration is
the
.BR runlevel (7)
event.  This is normally emitted by the
.BR telinit (8)
and
.BR shutdown (8)
tools.
.\"
.TP
.B reload-configuration

Requests that the
.BR init (8)
daemon reloads its configuration.

This command is generally not necessary since
.BR init (8)
watches its configuration directories with
.BR inotify (7)
and automatically reloads in cases of changes.

No jobs will be started by this command.
\"
.TP
.B version

Requests and outputs the version of the running init daemon.
.\"
.TP
.B log-priority
.RI [ PRIORITY ]

When called with a
.I PRIORITY
argument, it requests that the
.BR init (8)
daemon log all messages with that priority or greater.  This may be used
to both increase and decrease the volume of logged messages.

.I PRIORITY
may be one of
.IR debug ", " info ", " message ", " warn ", " error " or " fatal .

When called without argument, it requests the current minimum message
priority that the
.BR init (8)
daemon will log and ouputs to standard output.
.\"
.SH AUTHOR
Written by Scott James Remnant
.RB < scott@netsplit.com >
.\"
.SH REPORTING BUGS
Report bugs at
.RB < https://launchpad.net/upstart/+bugs >
.\"
.SH COPYRIGHT
Copyright \(co 2009 Canonical Ltd.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.SH SEE ALSO
.BR init (8)
.BR telinit (8)
.BR shutdown (8)
